[WasmFS] Make the Node backend optional for web builds by kleisauke · Pull Request #26608 · emscripten-core/emscripten

kleisauke · 2026-04-02T10:41:56Z

Previously, the WasmFS Node backend assumed Node.js was always available. This change allows building binaries that include Node backend stubs, so they can run in web environments.

Split out from #24733.

Previously, the WasmFS Node backend assumed Node.js was always available. This change allows building binaries that include Node backend stubs, so they can run in web environments.

kleisauke · 2026-04-02T10:43:46Z

src/lib/libwasmfs_node.js

+  _wasmfs_node_read: (fd, buf_p, len, pos, nread_p) => {},
+  _wasmfs_node_write: (fd, buf_p, len, pos, nwritten_p) => {},
+#else
+  $wasmfsNodeIsWindows: "!!process.platform.match(/^win/)",


This is a small drive-by fix. Previously, this would emit (when building on Linux):

var wasmfsNodeIsWindows = false;

in the JS output, which breaks when deploying these binaries on Windows.

As possible follow-up, we could also do:

Suggested change

$wasmfsNodeIsWindows: "!!process.platform.match(/^win/)",

$wasmfsNodeIsWindows: "!!globalThis.process?.platform.match(/^win/)",

This would allow a -sENVIRONMENT=node,web build to work on both Node.js and the web, using the same pattern as in other.test_wasmfs_nodefs_stubs, i.e.:

#include <emscripten/emscripten.h> #include <emscripten/wasmfs.h> EM_JS(bool, is_node, (), { return ENVIRONMENT_IS_NODE; }); backend_t wasmfs_create_root_dir() { return is_node() ? wasmfs_create_node_backend("") : wasmfs_create_memory_backend(); }

... PR #26624 addresses this.

sbc100 · 2026-04-02T15:35:03Z

src/lib/libwasmfs_node.js

+  _wasmfs_node_readlink: (path_p, target_p, bufsize) => {},
+  _wasmfs_node_close: (fd) => {},
+  _wasmfs_node_read: (fd, buf_p, len, pos, nread_p) => {},
+  _wasmfs_node_write: (fd, buf_p, len, pos, nwritten_p) => {},


Should these assert/abort or return non-zero?

Returning nothing/undefined here means they implicitly return zero to wasm

Good idea! Done (and simplified) with commit d30f7de.

sbc100 · 2026-04-02T15:35:38Z

src/lib/libwasmfs_node.js

@@ -5,7 +5,26 @@
 */


What about simply not allowing this file to be included at all it !ENVIRONMENT_MAY_BE_NODE?

That would lead to linker failures. For example, if I remove all these stubs and run ./test/runner other.test_wasmfs_nodefs_stubs, I see:

Details

wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_fstat_size wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_stat_size wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_open wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_open wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_close wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_close wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_read wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_write wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_ftruncate wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_truncate wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_get_mode wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_insert_file wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_insert_directory wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_symlink wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_rename wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_unlink wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_rmdir wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_readdir wasm-ld: error: /home/kleisauke/emscripten/cache/sysroot/lib/wasm32-emscripten/libwasmfs-debug.a(node_backend.o): undefined symbol: _wasmfs_node_readlink ...

I also thought about moving these stubs to native code and using weak linkage (like how wasmfs_create_root_dir() is handled), but this seemed easier.

Fair enough. I guess we should abort/assert in debug builds there though.

sbc100 · 2026-04-02T16:53:07Z

src/lib/libwasmfs_node.js

+      '}';
+  });
+
+  library[x] = eval(`(${t})`);


Why is eval needed here? I don't think we normally use eval in combination with modifyJSFunction

I copied-pasted this from wrapSyscallFunction():

emscripten/src/lib/libcore.js

Line 2596 in 34f6bcf

library[x] = eval(`(${t})`);

... but you're right, it seems unnecessary. Fixed with commit 4143136.

sbc100 · 2026-04-02T16:55:18Z

src/lib/libwasmfs_node.js

+  delete library[x + '__deps'];
+  t = modifyJSFunction(t, (args, body) => {
+    return `(${args}) => {\n` +
+      (ASSERTIONS ? "abort('wasmfs::NodeBackend is no-op when !ENVIRONMENT_MAY_BE_NODE');\n" : '') +


How about just abort('attempt to call nodejs backend function without ENVIRONMENT_MAY_BE_NODE)`.

I think the abort should exist even in release builds (you can make the error message optional if you like) since we never actually want a no-op behaviour here do we?

Commit eea0053 adjusts the error message.

I tried enabling abort() in release builds, but the wasmImports for these functions are somehow being DCE'd when building other.test_wasmfs_nodefs_stubs with -sASSERTIONS=0 or -O3, which is unexpected. I'll investigate.

... it was able to DCE away these functions as main() was empty, commit 4b86c1c fixes this.

Regarding abort() in release builds, perhaps that should be done as follow-up? I also noticed this in wrapSyscallFunction():

emscripten/src/lib/libcore.js

Lines 2514 to 2524 in 34f6bcf

// If a syscall uses FS, but !SYSCALLS_REQUIRE_FILESYSTEM, then the user

// has disabled the filesystem or we have proven some other way that this will

// not be called in practice, and do not need that code.

if (!SYSCALLS_REQUIRE_FILESYSTEM && t.includes('FS.')) {

library[x + '__deps'] = [];

t = modifyJSFunction(t, (args, body) => {

return `(${args}) => {\n` +

(ASSERTIONS ? "abort('it should not be possible to operate on streams when !SYSCALLS_REQUIRE_FILESYSTEM');\n" : '') +

'}';

});

}

sbc100

lgtm % nits

sbc100 · 2026-04-02T17:23:40Z

src/lib/libwasmfs_node.js

+      '}';
+  });
+
+  library[x] = t;


Just combine this with the line above?

sbc100 · 2026-04-02T17:24:01Z

src/lib/libwasmfs_node.js


-addToLibrary({
-  $wasmfsNodeIsWindows: !!process.platform.match(/^win/),
+var WasmFSNodeLibrary = {


JS names start with lowercase.

This avoids filesystem related functions from being DCE'd when building with `-sASSERTIONS=0` or `-O3`.

sbc100 · 2026-04-02T18:04:38Z

test/test_other.py

+        return 0;
+      }
+    ''')
+    self.run_process([EMCC, 'main.c', '-sWASMFS', '-sENVIRONMENT=web'])


I'm not sure I understand what this test is doing exactly. Its not actually running the result so what is it supposed to show?

Also, when -sENVIRONMENT=web I think ENVIRONMENT_IS_NODE not even be declared/defined so this program would just crash with undefined reference I think?

This was a test for the linker issue mentioned in comment #26608 (comment), but since commit d30f7de it's probably no longer relevant, as we can now be sure that these stubs are always in sync.

Commit d0c6c63 removes this test.

Also, when -sENVIRONMENT=web I think ENVIRONMENT_IS_NODE not even be declared/defined so this program would just crash with undefined reference I think?

I just checked this, but ENVIRONMENT_IS_NODE is also defined in -sENVIRONMENT=web builds.

... PR #26624 reinstates this test in test_browser.py.

sbc100 · 2026-04-02T18:05:32Z

test/test_other.py

    self.do_runf('access.c', cflags=['-sNODERAWFS'], args=[os.path.abspath('foo')])

+  def test_wasmfs_nodefs_stubs(self):
+    # This is equivalent to building with `-sWASMFS -sNODERAWFS`, except that the Wasm


I'm not sure I under stand that the This is here?

This comment should probably be part of the wasmfs_create_root_dir() hook.

It became superfluous after commit d30f7de.

sbc100

lgtm but maybe wait until #26609 lands.

Follow-up to #26608.

[WasmFS] Make the Node backend optional for web builds

26eaedc

Previously, the WasmFS Node backend assumed Node.js was always available. This change allows building binaries that include Node backend stubs, so they can run in web environments.

kleisauke commented Apr 2, 2026

View reviewed changes

kleisauke mentioned this pull request Apr 2, 2026

[WasmFS] Fix absolute path access under NODERAWFS #24733

Draft

sbc100 reviewed Apr 2, 2026

View reviewed changes

sbc100 approved these changes Apr 2, 2026

View reviewed changes

Incorporate feedback

d30f7de

sbc100 reviewed Apr 2, 2026

View reviewed changes

kleisauke added 2 commits April 2, 2026 19:00

Adjust error message

eea0053

Remove unnecessary eval()

4143136

sbc100 reviewed Apr 2, 2026

View reviewed changes

kleisauke added 3 commits April 2, 2026 19:40

Avoid empty main()

4b86c1c

This avoids filesystem related functions from being DCE'd when building with `-sASSERTIONS=0` or `-O3`.

Incorporate feedback

a2ab145

Cherry-pick from PR emscripten-core#26609

112bd63

sbc100 approved these changes Apr 2, 2026

View reviewed changes

sbc100 reviewed Apr 2, 2026

View reviewed changes

Remove superfluous test

d0c6c63

It became superfluous after commit d30f7de.

sbc100 approved these changes Apr 2, 2026

View reviewed changes

kleisauke merged commit be9f95b into emscripten-core:main Apr 4, 2026
38 checks passed

kleisauke deleted the wasmfs-allow-node-backend-on-web branch April 4, 2026 09:52

kleisauke mentioned this pull request Apr 4, 2026

[WasmFS] Make the Node backend multi-env compatible #26624

Merged

kleisauke added a commit that referenced this pull request Apr 6, 2026

[WasmFS] Make the Node backend multi-env compatible (#26624)

49f63ca

Follow-up to #26608.

	$wasmfsNodeIsWindows: "!!process.platform.match(/^win/)",
	$wasmfsNodeIsWindows: "!!globalThis.process?.platform.match(/^win/)",

	// If a syscall uses FS, but !SYSCALLS_REQUIRE_FILESYSTEM, then the user
	// has disabled the filesystem or we have proven some other way that this will
	// not be called in practice, and do not need that code.
	if (!SYSCALLS_REQUIRE_FILESYSTEM && t.includes('FS.')) {
	library[x + '__deps'] = [];
	t = modifyJSFunction(t, (args, body) => {
	return `(${args}) => {\n` +
	(ASSERTIONS ? "abort('it should not be possible to operate on streams when !SYSCALLS_REQUIRE_FILESYSTEM');\n" : '') +
	'}';
	});
	}

Conversation

kleisauke commented Apr 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants